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This Technical Note presents the Apple standard way to patch into the Apple IlGS Tool 
Dispatcher vectors. 



This Note presents MPW IlGS assembly-language code which provides the Apple-standard way 

for utilities to patch and unpatch the Tool Dispatcher vectors. If all Tool Dispatcher patches 
follow this protocol, patches can be installed and removed in any order, without ever accidentally 
unpatching somebody who patched in after the one getting removed. 

Using this protocol, each patch begins with a header in a standard form— a form recognizable by 
these routines (see PatchHeader). This way routines (like RemoveElOOOO) can scan 
through the list of patches and remove one from the middle. 

If your patch is going to stay in the system until shutdown, use this standard patch protocol 
anyway. This way other utilities can still recognize your patch and scan past it to find the next 
one. This Note is not just to show you a way to patch the tool dispatcher— it's to show you the 
way. If you patch tool dispatcher vectors in any other way, you strip other utilities of their 
ability to remove their patches. 

Of course, patching the Tool Dispatcher vectors slows down all toolbox calls, so you shouldn't 
patch the tool dispatcher without a pretty good reason. If you need to patch a toolbox function, it 
is usually better to do it by modifying a tool set's function pointer table instead of patching the 
dispatcher. 

The code in this note is specific to the System tool dispatch vectors ($E10000 and $E10004), but 
the same technique is recommended for the User tool dispatch vectors— just change $E 10000 to 
$E10008, $E10004 to $E1000C, and ToolPointerTable to UserToolPointerTable. 
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What Is This Stuff? 

This Note presents the following four routines. 

PatchHeader is the simplest patch function that obeys the protocol. This is where you put 
your own patch code. 

InstallE 10000 installs a patch into the patch chain. For example: 

pushlong #PatchHeader 
jsl InstallElOOOO 
ply 

ply ; remove the input parameter 

bcc noError ; error in A 

RemoveE 10000 removes a patch from the patch chain. For example: 

pushlong #PatchHeader 
jsl RemoveElOOOO 
ply 

ply ; remove the input parameter 

bcc noError ; error in A 

CheckPatch determines whether the specified address is the starting address of a standard 
patch. For example: 

pushlong #PatchHeader 
jsl CheckPatch 

ply 

ply ; remove the input parameter 

bcc validPatch 



First, here are some comments and global equates. 



**************************************************************************** 
* 

* Patch. elOOOO - Routines to patch into the toolbox dispatch 

* vectors at $elOOOO and $el0004. 

* 

* By Michael Lagae 

* Software Quality Assurance 

* GS Toolbox Test Team 
* 

* July 18, 1989 
* 

* Written for the MPW IIGS Assembler — Version l.lbl, 4/9/90 
* 

* Copyright 1989-1990 by Apple Computer, Inc. 
* 

**************************************************************************** 

case yes 
machine M65816 
string asis 
msb on 
print on 

export CheckPatch ; Check for a valid patch header. 
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export InstallElOOOO 
export RemoveElOOOO 
export PatchHeader 



Adds a patch into the toolbox vectors. 
Removes a toolbox dispatch vector patch. 
The simplest toolbox dispatch vector patch. 



*************************************************** 

* Equates - Various equates required by these routines. 
* 

versionNumber 

dispatchl 
dispatch2 
ToolPointerTable 
UserToolPointerTable 



equ $0100 

equ $elOOOO 
equ $el0004 
equ $el03c0 
equ $el03c8 



; The version number of this library. 

; The first toolbox dispatch vector. 

; The second toolbox dispatch vector. 

; Pointer to the active System TPT. 

; Pointer to the active User TPT. 



Error return values from the routines InstallElOOOO and RemoveElOOOO 



noError 

badHeaderError 
headerNotFoundError 



equ $0000 
equ $8001 
equ $8002 



Value returned if no error occurs. 
Patch header wasn't valid. 

Header to remove wasn't in the linked list. 



PatchHeader is the standard shell for the actual patch code. Your code goes in here, at 
NewDispatch2. When you get control at NewDispatch2, the function number is in X and 
there are two RTL addresses on the stack (pushed after the function's parameters). 

Your patch code does not care whether the tool call is being made through the $E10000 or 
$E10004 vector— in either case you get control with two RTL addresses on the stack. 

**************************************************************************** 

* PatchHeader - Header required of all routines that will be patched 

* into the toolbox dispatch vectors. 
* 

* Note; The code between nextlVector and NewDispatch2 must be included 

* for all calls. The code below NewDispatch2 only needs to be 

* included for patches that want to post patch the calls. 
* 

PatchHeader proc 

entry nextlVector , next2Vector 

entry dispatchlVector , dispatch2Vector 

entry NewDispatchl ,NewDispatch2 



nextlVector 

jml nextlVector 
next2Vector 

jml next2Vector 
dispatchlVector 

jml dispatchlVector 
dispatch2Vector 

jml dispatch2Vector 

anRtl rtl 



NewDispatchl 



phk 

pea anRtl- 1 



NewDispatch2 



Where dispatchl should go when finished. 

(Filled in by InstallElOOOO). 

Where dispatch2 should go when finished. 

(Filled in by InstallElOOOO). 

Holds the JML instruction from $elOOOO. 

(Filled in by InstallElOOOO). 

Holds the JML instruction from $el0004. 

(Filled in by InstallElOOOO). 

An RTL instruction. Its address will be 
pushed on the stack for dispatchl calls. 

Entry point for dispatchl toolbox vector. 

Push program bank. 

Push the address of a RTL. 

Entry point for dispatch2 toolbox vector. 



The following code should be included in the PatchHeader if the patch wants 
to perform post patching. This code will determine if the call that was made 
actually exists and if it does, post patching can occur. If the call doesn't 
exist, any pre-call routines can be executed, but the post patching shouldn't 
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; be attempted because the dispatcher will remove the second return address from 
; the stack, thus not returning to your post patching routines. 
; Stack equates for this routine. 



aLong 


equ 


$0001 




A temporary long value. 


oldDP 


equ 


aLong+4 




Where the direct page is saved to. 


oldTM 


eau 


oldDP+2 




Where the tool call number is saved. 




phx 






Save the call that's being made. 




phd 






Save the current direct page. 




Ida 


>ToolPointerTable+2 




Get the TPT to determine the number 




pha 






of tool sets loaded. 




Ida 


>ToolPointerTable 








pha 










tsc 






Set the direct page to the stack. 




ted 










txa 






See if this tool set exits. 




and 


#$00ff 








cmp 


[ aLong ] 




Is it larger than the number of tool sets? 




bcs 


@noCall 




JIF this tool set doesn't exist. 




asl 


a 








asl 


a 








tay 






Now get the pointer to the FPT . 




Ida 


r aLong 1 ,y 








tax 










iny 










iny 










Ida 


[aLong] ,y 








sta 


aLong+2 








stx 


aLong 








Ida 


oldTM 


r 


Get the function number. 




and 


#$ffOO 








xba 










cmp 


[ aLong] 


r 


Compare it to the number of entries in table 


gnoCall 










pla 




/ 


Remove aLong from the stack. 




pla 










pld 




r 


Restore the original direct page. 




plx 




r 


Recover the tool number. 



; At this point the carry flag is set if the tool call doesn't exist and clear 
; if the tool call exits. No post patching must occur if the carry flag is set. 

jmp next2Vector ; Go to the original $el0004 jump instruction. 



endp 

*********************************************************************** 

* CheckPatch - Checks the passed toolbox dispatch vector to see if it 

* points to a valid patch. 
* 

* Input: Passed via the stack following C conventions. 

* newPatchAddr (long) - Address of the patch routine. 

* 

* Output: 

* If newPatchAddr is a valid patch - 

* Carry clear 

* If newPatchAddr is not a valid patch - 

* Carry set 
* 

CheckPatch proc 

zprtl equ $01 ; The address for the rtl on our direct page. 

newPatchAddr equ zprtl+3 ; Address of patch (parameter to this routine). 

tsc ; Make the stack the direct page after saving 
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phd ; the current direct page, 

ted 
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Ida newPatchAddr+2 ; Simple check to check for a valid pointer, 

and #$ffOO 

bne BadPatch ; Wasn't zero, can't be a valid pointer. 

Ida [ newPatchAddr ] ; Check for the first JML instruction, 

and #$00ff 
cmp #$00 5c 
bne BadPatch 



Idy #$04 ; Check for the second JML instruction. 

Ida [ newPatchAddr ] , y 
and #$00ff 

cmp #$005c 
bne BadPatch 



Idy #$08 ; Check for the third JML instruction. 

Ida [ newPatchAddr ] , y 
and #$00ff 
cmp #$00 5c 
bne BadPatch 



Idy #$0c ; Check for the fourth JML instruction. 

Ida [ newPatchAddr ] , y 
and #$00ff 
cmp #$005c 
bne BadPatch 



Idy #$10 ; Check for the rtl and phk instructions. 

Ida [ newPatchAddr ] , y 
cmp #$4b6b 
bne BadPatch 



iny ; Check for the phk and pea instructions . 

Ida [ newPatchAddr ] , y 
cmp #$f44b 
bne BadPatch 

clc ; Calculate the address of the rtl instruction. 

Ida newPatchAddr 
adc #$000f 

Idy #$13 ; Check for address of the rtl instruction, 

cmp [ newPatchAddr ] , y 
bne BadPatch 



GoodPatch 

pld ; Restore the direct page and report 

clc ; that it was a good patch. 

rtl 



BadPatch 

pld ; Restore the direct page and report 

sec ; that something was wrong. 

rtl 



endp 

*************************************************** 

* InstallElOOOO - Sets the jump vector at $el0000 and $el0004 to point to 

* the passed new toolbox dispatch vector patch. This routine 

* also updates the linked lists so that more than one routine 

* can be patched into the dispatch vectors. 
* 

* Input: Passed via the stack following C conventions. 

* newPatchAddr (long) - Address of the patch routine. 
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* Output: 

* If an error occurred - 

* Carry set. Accumulator contains one of the following error codes: 

* badHeaderError 

* If no error occurred and patch was installed successfully - 

* Carry clear. Accumulator contains zero. 
* 

InstallElOOOO proc 



oldPatchAddr 
zprtl 
zpsize 
stack. 

newPatchAddr 
routine ) . 



equ $01 

equ oldPatchAddr+4 
equ zprtl-oldPatchAddr 

equ zprtl+3 



; Address of existing patch. 

; The address for the rtl. 

; Size of direct page we'll have on the 

; Address of patch (parameter to this 



tsc 
sec 

sbc #zpsize 

tcs 

phd 

ted 

php 

sei 

pei newPatchAddr+2 

pei newPatchAddr 

jsl CheckPatch 

plx 

plx 

bcc @1 

Idy #badHeaderError 

jmp Exit 

@1 Ida >dispatchl 

sta [newPatchAddr] 

Ida >dispatchl+2 

Idy #$02 

sta [ newPatchAddr ] , y 

Ida >dispatch2 

Idy #$04 

sta [ newPatchAddr ] , y 

Ida >dispatch2+2 

Idy #$06 

sta [ newPatchAddr ] , y 

Ida >dispatchl+3 

and #$00ff 

sta oldPatchAddr+2 

pha 

Ida >dispatchl+l 
sec 

sbc #$0011 

sta OldPatchAddr 

pha 

jsl CheckPatch 

plx 

plx 

bcs First 

Idy #$08 

Ida [ OldPatchAddr ] , y 

sta [ newPatchAddr ] , y 

Idy #$0a 

Ida [ OldPatchAddr ] , y 



Move the stack pointer to point beyond 
the direct page variables that we ' 11 
place on the stack. 

Save the direct page register. 
Set the direct page. 
Disable interrupts 



Check if patch header is valid. 

Remove the parameters from the stack. 
Report the badHeaderError if detected. 



Set up the nextlVector in the new patch. 
The JML instruction and low byte. 



The middle and upper bytes. 

Set up the next2Vector in the new patch. 

The JML instruction and low byte. 

The middle and upper bytes. 

See if there ' s already a patch in dispatchl . 

High byte of possible header address. 

Low byte of possible header address. 

JIF this will be the first patch installed. 
Set up the dispatchlVector in the new patch. 
The JML instruction and low byte. 
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sta [ newPatchAddr ] , y 
Idy #$0c 

Ida [ oldPatchAddr ] , y 
sta [ newPatchAddr ], y 
Idy #$0e 

Ida [ OldPatchAddr ] , y 
sta [ newPatchAddr ] , y 

bra Patchit 

First Idy #$08 

Ida >dispatchl 

sta [ newPatchAddr ], y 

Idy #$0a 

Ida >dispatchl+2 
sta [ newPatchAddr ] , y 

Idy #$0c 

Ida >dispatch2 

sta [ newPatchAddr ] , y 

Idy #$0e 

Ida >dispatch2+2 
sta [ newPatchAddr ] , y 



Patchit 



clc 

Ida newPatchAddr 
adc #$0015 
sta newPatchAddr 
xba 

and #$ffOO 
ora #$005c 
sta >dispatch2 
Ida newPatchAddr+1 
sta >dispatch2+2 



; The middle and upper bytes. 

; Set up the dispatch2Vector in the new patch. 
; The JML instruction and low byte. 

The middle and upper bytes. 
Now patch dispatchl and dispatch2 . 
Set up the dispatchlVector in the new patch. 
The JML instruction and low byte. 

; The middle and upper bytes. 

; Set up the dispatch2Vector in the new patch. 
; The JML instruction and low byte. 

; The middle and upper bytes. 

; Calculate the address of the new dispatch2. 

Mask in the JML instruction. 
The JML instruction and low byte. 
The middle and upper bytes . 





sec 






Calculate the address of the new 




Ida 


newPatchAddr 








sbc 


#$0004 








sta 


newPatchAddr 








xba 










and 


#$ffOO 




Mask in the JML instruction. 




ora 


#$005c 








sta 


>dispatchl 


} 


The JML instruction and low byte 




Ida 


newPatchAddr+1 








sta 


>dispatchl+2 


r 


The middle and upper bytes. 




Idy 


#noError 


r 


Report that all went well. 


Exit 


pip 




r 


Restore the interrupt state. 




pld 




/ 


Restore the previous direct page 




tsc 




r 


Restore the stack pointer. 




clc 










adc 


#zpsize 








tcs 










tya 




r 


Value to return. 




beq 


Snoerr 








sec 




7 


Report that there was an error. 




rtl 








@noerr 


clc 




/ 


Report that there was no error. 




rtl 










endp 
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********************************************************************** 



Removes the specified patch from the dispatchl and dispatch2 
vectors and updates the linked lists for the remaining 
toolbox patches . 



* Removes 100 00 
* 
* 
* 

* Input: Passed via the stack following C conventions. 

* patchToRemove (long) - Address of the patch to remove. 
* 

* Output: 

* If an error occurred - 

* Carry set. Accumulator contains one of the following error codes: 

* badHeaderError 

* headerNotFoundError 

* If no error occurred and patch was removed successfully - 

* Carry clear. Accumulator contains zero. 



RemoveElOOOO proc 



patchDispAddr 
byte ) . 
prevHeader 
zprtl 
zpsize 
stack . 

patchToRemove 
routine) . 



egu $01 

equ patchDispAddr+5 

equ prevHeader+4 

equ zprtl-patchDispAddr 

equ zprtl+3 



Address of existing patch (and 1 extra 

Used to search through the linked list. 

The address for the rtl. 

Size of direct page we ' 11 have on the 

Address of patch (parameter to this 



tsc 
sec 

sbc #zpsize 

tcs 

phd 

ted 

php 

sei 



Move the stack pointer to point beyond 
the direct page variables that we ' 11 
place on the stack. 

Save the direct page register. 
Set the direct page. 
Disable interrupts 



pei patchToRemove+2 

pei patchToRemove 

jsl CheckPatch 

plx 

plx 

bcc @1 

Idy #badHeaderError 
jmp Exit 



Check if patch header we were asked to 
remove is a valid header. 

Remove the parameters from the stack. 

Report the badHeaderError if detected. 



@1 clc 

Ida patchToRemove 

adc #$0011 

sta patchDispAddr+1 

Ida patchToRemove+2 

sta patchDispAddr+3 

Ida patchDispAddr 

and #$ffOO 

ora #$005c 

sta patchDispAddr 



; Create the JML instruction that would exist 
; if the patchToRemove was installed. 



; Mask in the JML instruction. 



cmp >dispatchl 
bne NotFirstOne 
Ida >dispatchl+2 
cmp patchDispAddr+2 
bne NotFirstOne 



; Check if the patch to remove is the first 
; patch installed. 



Ida [patchToRemove] 
sta >dispatchl 
Idy #$02 

Ida [ patchToRemove ] , y 



Restore the Dispatchl vector. 
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sta >dispatchl+2 
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Idy #$04 

Ida [ patchToRemove ] , y 
sta >dispatch2 
Idy #$06 

Ida [ patchToRemove ] , y 
sta >dispatch2+2 





bra 


NoErr 


NotFirstOne 




sec 






Ida 


>dispatchl+l 




sbc 


#$0011 




sta 


prevHeader 




Ida 


>dispatchl+3 




and 


#$00f f 




sta 


prevHeader+2 


@loop 


pei 


prevHeader+2 




pei 


prevHeader 




jsl 


CheckPatch 




plx 






plx 






bcc 


@2 




Idy 


#headerNotFoundError 




bra 


Exit 


@2 


Ida 


[ prevHeader ] 




cmp 


patchDispAddr 




bne 


@nope 




Idy 


#$02 




Ida 


[ prevHeader ] , y 




cmp 


patchDispAddr+2 




bne 


@nope 




Ida 


[ patchToRemove ] 




sta 


[ prevHeader ] 




Idy 


#$02 




Ida 


[ patchToRemove ] , y 




sta 


[prevHeader] ,y 




Idv 


#$04 




Ida 


[ patchToRemove ] , y 




sta 


[prevHeader] ,y 




Idy 


#$06 




Ida 


[ patchToRemove ] , y 




sta 


[prevHeader] ,y 




bra 


NoErr 


Snope 


Idy 


#$02 




Ida 


[ prevHeader ] , y 




tax 






Ida 


[ prevHeader ] 




sta 


prevHeader 




stx 


prevHeader +2 




sec 






Ida 


prevHeader+1 




sbc 


#$11 




sta 


prevHeader 




Ida 


prevHeader+3 




and 


#$00ff 




sta 


prevHeader+2 



; Restore the Dispatch2 vector. 



; Everything went well. 

; Assume that whatever is in dispatchl is a 

; patch and get the address of its header. 

; Low and middle bytes . 

; Upper byte of header address. 

; Check if it really is a valid header. 

; Remove the parameters from the stack. 

; Report that the patch that we asked to 

; remove wasn't found. 

; See if this patch points to patch we want 

; to remove. 



; Restore the nextlVector. 
; Restore the next2Vector. 



; Everything went well. 

; Get the address of the next patch header. 
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bra @loop 

NoErr Idy #noError 

Exit pip 
pld 
tsc 
clc 

adc #zpsize 

tcs 

tya 

beq @noerr 

sec 

rtl 

Snoerr clc 
rtl 

endp 

end 



; Now check this header. 

; Report that all went well. 

; Restore the interrupt state. 

; Restore the previous direct page register. 

; Restore the stack pointer. 



; Value to return. 

; Report that there was an error. 

; Report that there was no error. 



Further Reference 

• Apple IIgs Toolbox Reference 

• Apple IlGS Technical Note #73, Using User Tool Sets 
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